---
title: Parse tracking metadata
summary: Decodes a file-name tracking prefix back into structured metadata.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.Core
reference_type: package
operation_id: OP-13
trigger: PdfTrackingMetadata.Parse(string) invoked
---

# Parse tracking metadata

This operation reverses [Create tracking metadata](op-12-create-tracking-metadata.md) by decoding a file-name prefix back into a structured `PdfTrackingMetadata` instance. A known regex-capture-group defect means imaging intent and conversion type are never correctly recovered.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-13 |
| **Trigger** | Caller invokes `PdfTrackingMetadata.Parse(string prefix)` |
| **Inputs** | Tracking prefix string |
| **Outputs** | Populated `PdfTrackingMetadata`, or `null` |
| **Primary components** | `PdfAPI.Core.PdfTrackingMetadata.Parse` |
| **Entry point** | `PdfAPI.Core\PdfTrackingMetadata.cs` |

## Steps

1. Match the prefix against `(?<filePrefix>(?<type>.{1})(?<import>.{1})(?<appCode>[^_]+)_(?<fileId>[^\.+_]+))(_(?<fileIndex>\d+))?`. ([BR-35](../business-rules.md#br-35-tracking-prefix-parsing))
2. Return `null` when the pattern does not match. ([BR-36](../business-rules.md#br-36-non-matching-prefix-yields-no-metadata))
3. On a match, populate `FilePrefix`, `ApplicationCode`, and `FileId` (parsed as a `Guid`). ([BR-35](../business-rules.md#br-35-tracking-prefix-parsing))
4. Set `ShouldBeImaged` from group `importType` and `ConversionType` from group `conversionType`. ([BR-37](../business-rules.md#br-37-tracking-metadata-parse-defect))
   - This step reads capture groups named `importType` and `conversionType`, but the pattern in step 1 names them `import` and `type`. Both lookups therefore always return an empty string, so `Parse` always yields `ShouldBeImaged = false` and `ConversionType = Convert` regardless of the prefix — a defect in live (non-commented) code, not an inference: the group names do not match. ([BR-37](../business-rules.md#br-37-tracking-metadata-parse-defect))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["Parse(prefix)"]) --> Match{Matches tracking<br>prefix pattern?}
	Match -->|No| Null([Return null])
	Match -->|Yes| Populate["Populate FilePrefix,<br>ApplicationCode, FileId"]
	Populate --> Groups["Read importType/conversionType<br>groups (mismatched names)"]
	Groups --> Defect["ShouldBeImaged = false,<br>ConversionType = Convert (always)"]
	Defect --> Return([Return PdfTrackingMetadata])
```

## Failure and edge-case behavior
- The capture-group mismatch in step 4 means any workflow relying on round-tripping imaging intent or conversion type through the file-name prefix silently loses that data ([BR-37](../business-rules.md#br-37-tracking-metadata-parse-defect)).
- A prefix that does not match the pattern returns `null` rather than throwing ([BR-36](../business-rules.md#br-36-non-matching-prefix-yields-no-metadata)).

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Security and authorization](../security-authorization.md)

## Sources
- `PdfAPI.Core\PdfTrackingMetadata.cs`